<?xml version='1.0' encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <link href="cpip.css" rel="stylesheet" type="text/css" />
    <title>File: /Users/paulross/dev/Python-3.6.2/Include/pymem.h</title>
  </head>
  <body>
    <h1>File: /Users/paulross/dev/Python-3.6.2/Include/pymem.h</h1>
    <p>Green shading in the line number column
means the source is part of the translation unit, red means it is conditionally excluded.
Highlighted line numbers link to the translation unit page. Highlighted macros link to
the macro page.</p>
    <pre><a name="1" /><span class="True">       1:</span> <span class="k">/* The PyMem_ family:  low-level memory allocation interfaces.</span>
<a name="2" /><span class="True">       2:</span> <span class="k">   See objimpl.h for the PyObject_ memory family.</span>
<a name="3" /><span class="True">       3:</span> <span class="k">*/</span>
<a name="4" /><span class="True">       4:</span> 
<a name="5" /><span class="Maybe">       5:</span> <span class="f">#</span><span class="n">ifndef</span> <a href="macros_ref.html#_UHlfUFlNRU1fSF8w"><span class="b">Py_PYMEM_H</span></a>
<a name="6" /><span class="Maybe">       6:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_ref.html#_UHlfUFlNRU1fSF8w"><span class="b">Py_PYMEM_H</span></a>
<a name="7" /><span class="Maybe">       7:</span> 
<a name="8" /><span class="Maybe">       8:</span> <span class="f">#</span><span class="n">include</span> <span class="e">&quot;pyport.h&quot;</span>
<a name="9" /><span class="Maybe">       9:</span> 
<a name="10" /><span class="False">      10:</span> <span class="f">#</span><span class="n">ifdef</span> <span class="b">__cplusplus</span>
<a name="11" /><span class="False">      11:</span> <span class="m">extern</span> <span class="e">&quot;C&quot;</span> <span class="f">{</span>
<a name="12" /><span class="Maybe">      12:</span> <span class="f">#</span><span class="n">endif</span>
<a name="13" /><span class="Maybe">      13:</span> 
<a name="14" /><span class="Maybe">      14:</span> <span class="f">#</span><span class="n">ifndef</span> <span class="b">Py_LIMITED_API</span>
<a name="15" /><span class="Maybe">      15:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyMem_RawMalloc</span><span class="f">(</span><span class="b">size_t</span> <span class="b">size</span><span class="f">)</span><span class="f">;</span>
<a name="16" /><span class="Maybe">      16:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyMem_RawCalloc</span><span class="f">(</span><span class="b">size_t</span> <span class="b">nelem</span><span class="f">,</span> <span class="b">size_t</span> <span class="b">elsize</span><span class="f">)</span><span class="f">;</span>
<a name="17" /><span class="Maybe">      17:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyMem_RawRealloc</span><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="b">ptr</span><span class="f">,</span> <span class="b">size_t</span> <span class="b">new_size</span><span class="f">)</span><span class="f">;</span>
<a name="18" /><span class="Maybe">      18:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span><span class="f">)</span> <span class="b">PyMem_RawFree</span><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="b">ptr</span><span class="f">)</span><span class="f">;</span>
<a name="19" /><span class="Maybe">      19:</span> 
<a name="20" /><span class="Maybe">      20:</span> <span class="k">/* Configure the Python memory allocators. Pass NULL to use default</span>
<a name="21" /><span class="Maybe">      21:</span> <span class="k">   allocators. */</span>
<a name="22" /><span class="Maybe">      22:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">int</span><span class="f">)</span> <span class="b">_PyMem_SetupAllocators</span><span class="f">(</span><span class="m">const</span> <span class="m">char</span> <span class="f">*</span><span class="b">opt</span><span class="f">)</span><span class="f">;</span>
<a name="23" /><span class="Maybe">      23:</span> 
<a name="24" /><span class="Maybe">      24:</span> <span class="f">#</span><span class="n">ifdef</span> <a href="macros_ref.html#_V0lUSF9QWU1BTExPQ18w"><span class="b">WITH_PYMALLOC</span></a>
<a name="25" /><span class="Maybe">      25:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">int</span><span class="f">)</span> <span class="b">_PyMem_PymallocEnabled</span><span class="f">(</span><span class="m">void</span><span class="f">)</span><span class="f">;</span>
<a name="26" /><span class="Maybe">      26:</span> <span class="f">#</span><span class="n">endif</span>
<a name="27" /><span class="Maybe">      27:</span> 
<a name="28" /><span class="Maybe">      28:</span> <span class="k">/* Identifier of an address space (domain) in tracemalloc */</span>
<a name="29" /><span class="Maybe">      29:</span> <span class="m">typedef</span> <span class="m">unsigned</span> <span class="m">int</span> <span class="b">_PyTraceMalloc_domain_t</span><span class="f">;</span>
<a name="30" /><span class="Maybe">      30:</span> 
<a name="31" /><span class="Maybe">      31:</span> <span class="k">/* Track an allocated memory block in the tracemalloc module.</span>
<a name="32" /><span class="Maybe">      32:</span> <span class="k">   Return 0 on success, return -1 on error (failed to allocate memory to store</span>
<a name="33" /><span class="Maybe">      33:</span> <span class="k">   the trace).</span>
<a name="34" /><span class="Maybe">      34:</span> <span class="k"></span>
<a name="35" /><span class="Maybe">      35:</span> <span class="k">   Return -2 if tracemalloc is disabled.</span>
<a name="36" /><span class="Maybe">      36:</span> <span class="k"></span>
<a name="37" /><span class="Maybe">      37:</span> <span class="k">   If memory block is already tracked, update the existing trace. */</span>
<a name="38" /><span class="Maybe">      38:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">int</span><span class="f">)</span> <span class="b">_PyTraceMalloc_Track</span><span class="f">(</span>
<a name="39" /><span class="Maybe">      39:</span>     <span class="b">_PyTraceMalloc_domain_t</span> <span class="b">domain</span><span class="f">,</span>
<a name="40" /><span class="Maybe">      40:</span>     <span class="b">uintptr_t</span> <span class="b">ptr</span><span class="f">,</span>
<a name="41" /><span class="Maybe">      41:</span>     <span class="b">size_t</span> <span class="b">size</span><span class="f">)</span><span class="f">;</span>
<a name="42" /><span class="Maybe">      42:</span> 
<a name="43" /><span class="Maybe">      43:</span> <span class="k">/* Untrack an allocated memory block in the tracemalloc module.</span>
<a name="44" /><span class="Maybe">      44:</span> <span class="k">   Do nothing if the block was not tracked.</span>
<a name="45" /><span class="Maybe">      45:</span> <span class="k"></span>
<a name="46" /><span class="Maybe">      46:</span> <span class="k">   Return -2 if tracemalloc is disabled, otherwise return 0. */</span>
<a name="47" /><span class="Maybe">      47:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">int</span><span class="f">)</span> <span class="b">_PyTraceMalloc_Untrack</span><span class="f">(</span>
<a name="48" /><span class="Maybe">      48:</span>     <span class="b">_PyTraceMalloc_domain_t</span> <span class="b">domain</span><span class="f">,</span>
<a name="49" /><span class="Maybe">      49:</span>     <span class="b">uintptr_t</span> <span class="b">ptr</span><span class="f">)</span><span class="f">;</span>
<a name="50" /><span class="Maybe">      50:</span> 
<a name="51" /><span class="Maybe">      51:</span> <span class="k">/* Get the traceback where a memory block was allocated.</span>
<a name="52" /><span class="Maybe">      52:</span> <span class="k"></span>
<a name="53" /><span class="Maybe">      53:</span> <span class="k">   Return a tuple of (filename: str, lineno: int) tuples.</span>
<a name="54" /><span class="Maybe">      54:</span> <span class="k"></span>
<a name="55" /><span class="Maybe">      55:</span> <span class="k">   Return None if the tracemalloc module is disabled or if the memory block</span>
<a name="56" /><span class="Maybe">      56:</span> <span class="k">   is not tracked by tracemalloc.</span>
<a name="57" /><span class="Maybe">      57:</span> <span class="k"></span>
<a name="58" /><span class="Maybe">      58:</span> <span class="k">   Raise an exception and return NULL on error. */</span>
<a name="59" /><span class="Maybe">      59:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="b">PyObject</span><span class="f">*</span><span class="f">)</span> <span class="b">_PyTraceMalloc_GetTraceback</span><span class="f">(</span>
<a name="60" /><span class="Maybe">      60:</span>     <span class="b">_PyTraceMalloc_domain_t</span> <span class="b">domain</span><span class="f">,</span>
<a name="61" /><span class="Maybe">      61:</span>     <span class="b">uintptr_t</span> <span class="b">ptr</span><span class="f">)</span><span class="f">;</span>
<a name="62" /><span class="Maybe">      62:</span> <span class="f">#</span><span class="n">endif</span>   <span class="k">/* !Py_LIMITED_API */</span>
<a name="63" /><span class="Maybe">      63:</span> 
<a name="64" /><span class="Maybe">      64:</span> 
<a name="65" /><span class="Maybe">      65:</span> <span class="k">/* BEWARE:</span>
<a name="66" /><span class="Maybe">      66:</span> <span class="k"></span>
<a name="67" /><span class="Maybe">      67:</span> <span class="k">   Each interface exports both functions and macros.  Extension modules should</span>
<a name="68" /><span class="Maybe">      68:</span> <span class="k">   use the functions, to ensure binary compatibility across Python versions.</span>
<a name="69" /><span class="Maybe">      69:</span> <span class="k">   Because the Python implementation is free to change internal details, and</span>
<a name="70" /><span class="Maybe">      70:</span> <span class="k">   the macros may (or may not) expose details for speed, if you do use the</span>
<a name="71" /><span class="Maybe">      71:</span> <span class="k">   macros you must recompile your extensions with each Python release.</span>
<a name="72" /><span class="Maybe">      72:</span> <span class="k"></span>
<a name="73" /><span class="Maybe">      73:</span> <span class="k">   Never mix calls to PyMem_ with calls to the platform malloc/realloc/</span>
<a name="74" /><span class="Maybe">      74:</span> <span class="k">   calloc/free.  For example, on Windows different DLLs may end up using</span>
<a name="75" /><span class="Maybe">      75:</span> <span class="k">   different heaps, and if you use PyMem_Malloc you&apos;ll get the memory from the</span>
<a name="76" /><span class="Maybe">      76:</span> <span class="k">   heap used by the Python DLL; it could be a disaster if you free()&apos;ed that</span>
<a name="77" /><span class="Maybe">      77:</span> <span class="k">   directly in your own extension.  Using PyMem_Free instead ensures Python</span>
<a name="78" /><span class="Maybe">      78:</span> <span class="k">   can return the memory to the proper heap.  As another example, in</span>
<a name="79" /><span class="Maybe">      79:</span> <span class="k">   PYMALLOC_DEBUG mode, Python wraps all calls to all PyMem_ and PyObject_</span>
<a name="80" /><span class="Maybe">      80:</span> <span class="k">   memory functions in special debugging wrappers that add additional</span>
<a name="81" /><span class="Maybe">      81:</span> <span class="k">   debugging info to dynamic memory blocks.  The system routines have no idea</span>
<a name="82" /><span class="Maybe">      82:</span> <span class="k">   what to do with that stuff, and the Python wrappers have no idea what to do</span>
<a name="83" /><span class="Maybe">      83:</span> <span class="k">   with raw blocks obtained directly by the system routines then.</span>
<a name="84" /><span class="Maybe">      84:</span> <span class="k"></span>
<a name="85" /><span class="Maybe">      85:</span> <span class="k">   The GIL must be held when using these APIs.</span>
<a name="86" /><span class="Maybe">      86:</span> <span class="k">*/</span>
<a name="87" /><span class="Maybe">      87:</span> 
<a name="88" /><span class="Maybe">      88:</span> <span class="k">/*</span>
<a name="89" /><span class="Maybe">      89:</span> <span class="k"> * Raw memory interface</span>
<a name="90" /><span class="Maybe">      90:</span> <span class="k"> * ====================</span>
<a name="91" /><span class="Maybe">      91:</span> <span class="k"> */</span>
<a name="92" /><span class="Maybe">      92:</span> 
<a name="93" /><span class="Maybe">      93:</span> <span class="k">/* Functions</span>
<a name="94" /><span class="Maybe">      94:</span> <span class="k"></span>
<a name="95" /><span class="Maybe">      95:</span> <span class="k">   Functions supplying platform-independent semantics for malloc/realloc/</span>
<a name="96" /><span class="Maybe">      96:</span> <span class="k">   free.  These functions make sure that allocating 0 bytes returns a distinct</span>
<a name="97" /><span class="Maybe">      97:</span> <span class="k">   non-NULL pointer (whenever possible -- if we&apos;re flat out of memory, NULL</span>
<a name="98" /><span class="Maybe">      98:</span> <span class="k">   may be returned), even if the platform malloc and realloc don&apos;t.</span>
<a name="99" /><span class="Maybe">      99:</span> <span class="k">   Returned pointers must be checked for NULL explicitly.  No action is</span>
<a name="100" /><span class="Maybe">     100:</span> <span class="k">   performed on failure (no exception is set, no warning is printed, etc).</span>
<a name="101" /><span class="Maybe">     101:</span> <span class="k">*/</span>
<a name="102" /><span class="Maybe">     102:</span> 
<a name="103" /><span class="Maybe">     103:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyMem_Malloc</span><span class="f">(</span><span class="b">size_t</span> <span class="b">size</span><span class="f">)</span><span class="f">;</span>
<a name="104" /><span class="Maybe">     104:</span> <span class="f">#</span><span class="n">if</span> <span class="f">!</span><span class="b">defined</span><span class="f">(</span><span class="b">Py_LIMITED_API</span><span class="f">)</span> <span class="f">||</span> <span class="b">Py_LIMITED_API</span><span class="f">+</span><span class="c">0</span> <span class="f">&gt;=</span> <span class="c">0x03050000</span>
<a name="105" /><span class="Maybe">     105:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyMem_Calloc</span><span class="f">(</span><span class="b">size_t</span> <span class="b">nelem</span><span class="f">,</span> <span class="b">size_t</span> <span class="b">elsize</span><span class="f">)</span><span class="f">;</span>
<a name="106" /><span class="Maybe">     106:</span> <span class="f">#</span><span class="n">endif</span>
<a name="107" /><span class="Maybe">     107:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyMem_Realloc</span><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="b">ptr</span><span class="f">,</span> <span class="b">size_t</span> <span class="b">new_size</span><span class="f">)</span><span class="f">;</span>
<a name="108" /><span class="Maybe">     108:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span><span class="f">)</span> <span class="b">PyMem_Free</span><span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="b">ptr</span><span class="f">)</span><span class="f">;</span>
<a name="109" /><span class="Maybe">     109:</span> 
<a name="110" /><span class="Maybe">     110:</span> <span class="f">#</span><span class="n">ifndef</span> <span class="b">Py_LIMITED_API</span>
<a name="111" /><span class="Maybe">     111:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">char</span> <span class="f">*</span><span class="f">)</span> <span class="b">_PyMem_RawStrdup</span><span class="f">(</span><span class="m">const</span> <span class="m">char</span> <span class="f">*</span><span class="b">str</span><span class="f">)</span><span class="f">;</span>
<a name="112" /><span class="Maybe">     112:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">char</span> <span class="f">*</span><span class="f">)</span> <span class="b">_PyMem_Strdup</span><span class="f">(</span><span class="m">const</span> <span class="m">char</span> <span class="f">*</span><span class="b">str</span><span class="f">)</span><span class="f">;</span>
<a name="113" /><span class="Maybe">     113:</span> <span class="f">#</span><span class="n">endif</span>
<a name="114" /><span class="Maybe">     114:</span> 
<a name="115" /><span class="Maybe">     115:</span> <span class="k">/* Macros. */</span>
<a name="116" /><span class="Maybe">     116:</span> 
<a name="117" /><span class="Maybe">     117:</span> <span class="k">/* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL</span>
<a name="118" /><span class="Maybe">     118:</span> <span class="k">   for malloc(0), which would be treated as an error. Some platforms</span>
<a name="119" /><span class="Maybe">     119:</span> <span class="k">   would return a pointer with no memory behind it, which would break</span>
<a name="120" /><span class="Maybe">     120:</span> <span class="k">   pymalloc. To solve these problems, allocate an extra byte. */</span>
<a name="121" /><span class="Maybe">     121:</span> <span class="k">/* Returns NULL to indicate error if a negative size or size larger than</span>
<a name="122" /><span class="Maybe">     122:</span> <span class="k">   Py_ssize_t can represent is supplied.  Helps prevents security holes. */</span>
<a name="123" /><span class="Maybe">     123:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_ref.html#_UHlNZW1fTUFMTE9DXzA_"><span class="b">PyMem_MALLOC</span></a><span class="f">(</span><span class="b">n</span><span class="f">)</span>         <span class="b">PyMem_Malloc</span><span class="f">(</span><span class="b">n</span><span class="f">)</span>
<a name="124" /><span class="Maybe">     124:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_noref.html#_UHlNZW1fUkVBTExPQ18w"><span class="b">PyMem_REALLOC</span></a><span class="f">(</span><span class="b">p</span><span class="f">,</span> <span class="b">n</span><span class="f">)</span>     <span class="b">PyMem_Realloc</span><span class="f">(</span><span class="b">p</span><span class="f">,</span> <span class="b">n</span><span class="f">)</span>
<a name="125" /><span class="Maybe">     125:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_ref.html#_UHlNZW1fRlJFRV8w"><span class="b">PyMem_FREE</span></a><span class="f">(</span><span class="b">p</span><span class="f">)</span>           <span class="b">PyMem_Free</span><span class="f">(</span><span class="b">p</span><span class="f">)</span>
<a name="126" /><span class="Maybe">     126:</span> 
<a name="127" /><span class="Maybe">     127:</span> <span class="k">/*</span>
<a name="128" /><span class="Maybe">     128:</span> <span class="k"> * Type-oriented memory interface</span>
<a name="129" /><span class="Maybe">     129:</span> <span class="k"> * ==============================</span>
<a name="130" /><span class="Maybe">     130:</span> <span class="k"> *</span>
<a name="131" /><span class="Maybe">     131:</span> <span class="k"> * Allocate memory for n objects of the given type.  Returns a new pointer</span>
<a name="132" /><span class="Maybe">     132:</span> <span class="k"> * or NULL if the request was too large or memory allocation failed.  Use</span>
<a name="133" /><span class="Maybe">     133:</span> <span class="k"> * these macros rather than doing the multiplication yourself so that proper</span>
<a name="134" /><span class="Maybe">     134:</span> <span class="k"> * overflow checking is always done.</span>
<a name="135" /><span class="Maybe">     135:</span> <span class="k"> */</span>
<a name="136" /><span class="Maybe">     136:</span> 
<a name="137" /><span class="Maybe">     137:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_noref.html#_UHlNZW1fTmV3XzA_"><span class="b">PyMem_New</span></a><span class="f">(</span><span class="b">type</span><span class="f">,</span> <span class="b">n</span><span class="f">)</span> \
<a name="138" /><span class="Maybe">     138:</span>   <span class="f">(</span> <span class="f">(</span><span class="f">(</span><span class="b">size_t</span><span class="f">)</span><span class="f">(</span><span class="b">n</span><span class="f">)</span> <span class="f">&gt;</span> <a href="macros_ref.html#_UFlfU1NJWkVfVF9NQVhfMA__"><span class="b">PY_SSIZE_T_MAX</span></a> <span class="f">/</span> <span class="m">sizeof</span><span class="f">(</span><span class="b">type</span><span class="f">)</span><span class="f">)</span> <span class="f">?</span> <a href="macros_ref.html#_TlVMTF8w"><span class="b">NULL</span></a> <span class="f">:</span>    \
<a name="139" /><span class="Maybe">     139:</span>     <span class="f">(</span> <span class="f">(</span><span class="b">type</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyMem_Malloc</span><span class="f">(</span><span class="f">(</span><span class="b">n</span><span class="f">)</span> <span class="f">*</span> <span class="m">sizeof</span><span class="f">(</span><span class="b">type</span><span class="f">)</span><span class="f">)</span> <span class="f">)</span> <span class="f">)</span>
<a name="140" /><span class="Maybe">     140:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_ref.html#_UHlNZW1fTkVXXzA_"><span class="b">PyMem_NEW</span></a><span class="f">(</span><span class="b">type</span><span class="f">,</span> <span class="b">n</span><span class="f">)</span> \
<a name="141" /><span class="Maybe">     141:</span>   <span class="f">(</span> <span class="f">(</span><span class="f">(</span><span class="b">size_t</span><span class="f">)</span><span class="f">(</span><span class="b">n</span><span class="f">)</span> <span class="f">&gt;</span> <a href="macros_ref.html#_UFlfU1NJWkVfVF9NQVhfMA__"><span class="b">PY_SSIZE_T_MAX</span></a> <span class="f">/</span> <span class="m">sizeof</span><span class="f">(</span><span class="b">type</span><span class="f">)</span><span class="f">)</span> <span class="f">?</span> <a href="macros_ref.html#_TlVMTF8w"><span class="b">NULL</span></a> <span class="f">:</span>    \
<a name="142" /><span class="Maybe">     142:</span>     <span class="f">(</span> <span class="f">(</span><span class="b">type</span> <span class="f">*</span><span class="f">)</span> <a href="macros_ref.html#_UHlNZW1fTUFMTE9DXzA_"><span class="b">PyMem_MALLOC</span></a><span class="f">(</span><span class="f">(</span><span class="b">n</span><span class="f">)</span> <span class="f">*</span> <span class="m">sizeof</span><span class="f">(</span><span class="b">type</span><span class="f">)</span><span class="f">)</span> <span class="f">)</span> <span class="f">)</span>
<a name="143" /><span class="Maybe">     143:</span> 
<a name="144" /><span class="Maybe">     144:</span> <span class="k">/*</span>
<a name="145" /><span class="Maybe">     145:</span> <span class="k"> * The value of (p) is always clobbered by this macro regardless of success.</span>
<a name="146" /><span class="Maybe">     146:</span> <span class="k"> * The caller MUST check if (p) is NULL afterwards and deal with the memory</span>
<a name="147" /><span class="Maybe">     147:</span> <span class="k"> * error if so.  This means the original value of (p) MUST be saved for the</span>
<a name="148" /><span class="Maybe">     148:</span> <span class="k"> * caller&apos;s memory error handler to not lose track of it.</span>
<a name="149" /><span class="Maybe">     149:</span> <span class="k"> */</span>
<a name="150" /><span class="Maybe">     150:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_noref.html#_UHlNZW1fUmVzaXplXzA_"><span class="b">PyMem_Resize</span></a><span class="f">(</span><span class="b">p</span><span class="f">,</span> <span class="b">type</span><span class="f">,</span> <span class="b">n</span><span class="f">)</span> \
<a name="151" /><span class="Maybe">     151:</span>   <span class="f">(</span> <span class="f">(</span><span class="b">p</span><span class="f">)</span> <span class="f">=</span> <span class="f">(</span><span class="f">(</span><span class="b">size_t</span><span class="f">)</span><span class="f">(</span><span class="b">n</span><span class="f">)</span> <span class="f">&gt;</span> <a href="macros_ref.html#_UFlfU1NJWkVfVF9NQVhfMA__"><span class="b">PY_SSIZE_T_MAX</span></a> <span class="f">/</span> <span class="m">sizeof</span><span class="f">(</span><span class="b">type</span><span class="f">)</span><span class="f">)</span> <span class="f">?</span> <a href="macros_ref.html#_TlVMTF8w"><span class="b">NULL</span></a> <span class="f">:</span>    \
<a name="152" /><span class="Maybe">     152:</span>     <span class="f">(</span><span class="b">type</span> <span class="f">*</span><span class="f">)</span> <span class="b">PyMem_Realloc</span><span class="f">(</span><span class="f">(</span><span class="b">p</span><span class="f">)</span><span class="f">,</span> <span class="f">(</span><span class="b">n</span><span class="f">)</span> <span class="f">*</span> <span class="m">sizeof</span><span class="f">(</span><span class="b">type</span><span class="f">)</span><span class="f">)</span> <span class="f">)</span>
<a name="153" /><span class="Maybe">     153:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_noref.html#_UHlNZW1fUkVTSVpFXzA_"><span class="b">PyMem_RESIZE</span></a><span class="f">(</span><span class="b">p</span><span class="f">,</span> <span class="b">type</span><span class="f">,</span> <span class="b">n</span><span class="f">)</span> \
<a name="154" /><span class="Maybe">     154:</span>   <span class="f">(</span> <span class="f">(</span><span class="b">p</span><span class="f">)</span> <span class="f">=</span> <span class="f">(</span><span class="f">(</span><span class="b">size_t</span><span class="f">)</span><span class="f">(</span><span class="b">n</span><span class="f">)</span> <span class="f">&gt;</span> <a href="macros_ref.html#_UFlfU1NJWkVfVF9NQVhfMA__"><span class="b">PY_SSIZE_T_MAX</span></a> <span class="f">/</span> <span class="m">sizeof</span><span class="f">(</span><span class="b">type</span><span class="f">)</span><span class="f">)</span> <span class="f">?</span> <a href="macros_ref.html#_TlVMTF8w"><span class="b">NULL</span></a> <span class="f">:</span>    \
<a name="155" /><span class="Maybe">     155:</span>     <span class="f">(</span><span class="b">type</span> <span class="f">*</span><span class="f">)</span> <a href="macros_noref.html#_UHlNZW1fUkVBTExPQ18w"><span class="b">PyMem_REALLOC</span></a><span class="f">(</span><span class="f">(</span><span class="b">p</span><span class="f">)</span><span class="f">,</span> <span class="f">(</span><span class="b">n</span><span class="f">)</span> <span class="f">*</span> <span class="m">sizeof</span><span class="f">(</span><span class="b">type</span><span class="f">)</span><span class="f">)</span> <span class="f">)</span>
<a name="156" /><span class="Maybe">     156:</span> 
<a name="157" /><span class="Maybe">     157:</span> <span class="k">/* PyMem{Del,DEL} are left over from ancient days, and shouldn&apos;t be used</span>
<a name="158" /><span class="Maybe">     158:</span> <span class="k"> * anymore.  They&apos;re just confusing aliases for PyMem_{Free,FREE} now.</span>
<a name="159" /><span class="Maybe">     159:</span> <span class="k"> */</span>
<a name="160" /><span class="Maybe">     160:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_noref.html#_UHlNZW1fRGVsXzA_"><span class="b">PyMem_Del</span></a>        <span class="b">PyMem_Free</span>
<a name="161" /><span class="Maybe">     161:</span> <span class="f">#</span><span class="n">define</span> <a href="macros_noref.html#_UHlNZW1fREVMXzA_"><span class="b">PyMem_DEL</span></a>        <a href="macros_ref.html#_UHlNZW1fRlJFRV8w"><span class="b">PyMem_FREE</span></a>
<a name="162" /><span class="Maybe">     162:</span> 
<a name="163" /><span class="Maybe">     163:</span> <span class="f">#</span><span class="n">ifndef</span> <span class="b">Py_LIMITED_API</span>
<a name="164" /><span class="Maybe">     164:</span> <span class="m">typedef</span> <span class="m">enum</span> <span class="f">{</span>
<a name="165" /><span class="Maybe">     165:</span>     <span class="k">/* PyMem_RawMalloc(), PyMem_RawRealloc() and PyMem_RawFree() */</span>
<a name="166" /><span class="Maybe">     166:</span>     <span class="b">PYMEM_DOMAIN_RAW</span><span class="f">,</span>
<a name="167" /><span class="Maybe">     167:</span> 
<a name="168" /><span class="Maybe">     168:</span>     <span class="k">/* PyMem_Malloc(), PyMem_Realloc() and PyMem_Free() */</span>
<a name="169" /><span class="Maybe">     169:</span>     <span class="b">PYMEM_DOMAIN_MEM</span><span class="f">,</span>
<a name="170" /><span class="Maybe">     170:</span> 
<a name="171" /><span class="Maybe">     171:</span>     <span class="k">/* PyObject_Malloc(), PyObject_Realloc() and PyObject_Free() */</span>
<a name="172" /><span class="Maybe">     172:</span>     <span class="b">PYMEM_DOMAIN_OBJ</span>
<a name="173" /><span class="Maybe">     173:</span> <span class="f">}</span> <span class="b">PyMemAllocatorDomain</span><span class="f">;</span>
<a name="174" /><span class="Maybe">     174:</span> 
<a name="175" /><span class="Maybe">     175:</span> <span class="m">typedef</span> <span class="m">struct</span> <span class="f">{</span>
<a name="176" /><span class="Maybe">     176:</span>     <span class="k">/* user context passed as the first argument to the 4 functions */</span>
<a name="177" /><span class="Maybe">     177:</span>     <span class="m">void</span> <span class="f">*</span><span class="b">ctx</span><span class="f">;</span>
<a name="178" /><span class="Maybe">     178:</span> 
<a name="179" /><span class="Maybe">     179:</span>     <span class="k">/* allocate a memory block */</span>
<a name="180" /><span class="Maybe">     180:</span>     <span class="m">void</span><span class="f">*</span> <span class="f">(</span><span class="f">*</span><span class="b">malloc</span><span class="f">)</span> <span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="b">ctx</span><span class="f">,</span> <span class="b">size_t</span> <span class="b">size</span><span class="f">)</span><span class="f">;</span>
<a name="181" /><span class="Maybe">     181:</span> 
<a name="182" /><span class="Maybe">     182:</span>     <span class="k">/* allocate a memory block initialized by zeros */</span>
<a name="183" /><span class="Maybe">     183:</span>     <span class="m">void</span><span class="f">*</span> <span class="f">(</span><span class="f">*</span><span class="b">calloc</span><span class="f">)</span> <span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="b">ctx</span><span class="f">,</span> <span class="b">size_t</span> <span class="b">nelem</span><span class="f">,</span> <span class="b">size_t</span> <span class="b">elsize</span><span class="f">)</span><span class="f">;</span>
<a name="184" /><span class="Maybe">     184:</span> 
<a name="185" /><span class="Maybe">     185:</span>     <span class="k">/* allocate or resize a memory block */</span>
<a name="186" /><span class="Maybe">     186:</span>     <span class="m">void</span><span class="f">*</span> <span class="f">(</span><span class="f">*</span><span class="b">realloc</span><span class="f">)</span> <span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="b">ctx</span><span class="f">,</span> <span class="m">void</span> <span class="f">*</span><span class="b">ptr</span><span class="f">,</span> <span class="b">size_t</span> <span class="b">new_size</span><span class="f">)</span><span class="f">;</span>
<a name="187" /><span class="Maybe">     187:</span> 
<a name="188" /><span class="Maybe">     188:</span>     <span class="k">/* release a memory block */</span>
<a name="189" /><span class="Maybe">     189:</span>     <span class="m">void</span> <span class="f">(</span><span class="f">*</span><span class="b">free</span><span class="f">)</span> <span class="f">(</span><span class="m">void</span> <span class="f">*</span><span class="b">ctx</span><span class="f">,</span> <span class="m">void</span> <span class="f">*</span><span class="b">ptr</span><span class="f">)</span><span class="f">;</span>
<a name="190" /><span class="Maybe">     190:</span> <span class="f">}</span> <span class="b">PyMemAllocatorEx</span><span class="f">;</span>
<a name="191" /><span class="Maybe">     191:</span> 
<a name="192" /><span class="Maybe">     192:</span> <span class="k">/* Get the memory block allocator of the specified domain. */</span>
<a name="193" /><span class="Maybe">     193:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span><span class="f">)</span> <span class="b">PyMem_GetAllocator</span><span class="f">(</span><span class="b">PyMemAllocatorDomain</span> <span class="b">domain</span><span class="f">,</span>
<a name="194" /><span class="Maybe">     194:</span>                                     <span class="b">PyMemAllocatorEx</span> <span class="f">*</span><span class="b">allocator</span><span class="f">)</span><span class="f">;</span>
<a name="195" /><span class="Maybe">     195:</span> 
<a name="196" /><span class="Maybe">     196:</span> <span class="k">/* Set the memory block allocator of the specified domain.</span>
<a name="197" /><span class="Maybe">     197:</span> <span class="k"></span>
<a name="198" /><span class="Maybe">     198:</span> <span class="k">   The new allocator must return a distinct non-NULL pointer when requesting</span>
<a name="199" /><span class="Maybe">     199:</span> <span class="k">   zero bytes.</span>
<a name="200" /><span class="Maybe">     200:</span> <span class="k"></span>
<a name="201" /><span class="Maybe">     201:</span> <span class="k">   For the PYMEM_DOMAIN_RAW domain, the allocator must be thread-safe: the GIL</span>
<a name="202" /><span class="Maybe">     202:</span> <span class="k">   is not held when the allocator is called.</span>
<a name="203" /><span class="Maybe">     203:</span> <span class="k"></span>
<a name="204" /><span class="Maybe">     204:</span> <span class="k">   If the new allocator is not a hook (don&apos;t call the previous allocator), the</span>
<a name="205" /><span class="Maybe">     205:</span> <span class="k">   PyMem_SetupDebugHooks() function must be called to reinstall the debug hooks</span>
<a name="206" /><span class="Maybe">     206:</span> <span class="k">   on top on the new allocator. */</span>
<a name="207" /><span class="Maybe">     207:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span><span class="f">)</span> <span class="b">PyMem_SetAllocator</span><span class="f">(</span><span class="b">PyMemAllocatorDomain</span> <span class="b">domain</span><span class="f">,</span>
<a name="208" /><span class="Maybe">     208:</span>                                     <span class="b">PyMemAllocatorEx</span> <span class="f">*</span><span class="b">allocator</span><span class="f">)</span><span class="f">;</span>
<a name="209" /><span class="Maybe">     209:</span> 
<a name="210" /><span class="Maybe">     210:</span> <span class="k">/* Setup hooks to detect bugs in the following Python memory allocator</span>
<a name="211" /><span class="Maybe">     211:</span> <span class="k">   functions:</span>
<a name="212" /><span class="Maybe">     212:</span> <span class="k"></span>
<a name="213" /><span class="Maybe">     213:</span> <span class="k">   - PyMem_RawMalloc(), PyMem_RawRealloc(), PyMem_RawFree()</span>
<a name="214" /><span class="Maybe">     214:</span> <span class="k">   - PyMem_Malloc(), PyMem_Realloc(), PyMem_Free()</span>
<a name="215" /><span class="Maybe">     215:</span> <span class="k">   - PyObject_Malloc(), PyObject_Realloc() and PyObject_Free()</span>
<a name="216" /><span class="Maybe">     216:</span> <span class="k"></span>
<a name="217" /><span class="Maybe">     217:</span> <span class="k">   Newly allocated memory is filled with the byte 0xCB, freed memory is filled</span>
<a name="218" /><span class="Maybe">     218:</span> <span class="k">   with the byte 0xDB. Additionnal checks:</span>
<a name="219" /><span class="Maybe">     219:</span> <span class="k"></span>
<a name="220" /><span class="Maybe">     220:</span> <span class="k">   - detect API violations, ex: PyObject_Free() called on a buffer allocated</span>
<a name="221" /><span class="Maybe">     221:</span> <span class="k">     by PyMem_Malloc()</span>
<a name="222" /><span class="Maybe">     222:</span> <span class="k">   - detect write before the start of the buffer (buffer underflow)</span>
<a name="223" /><span class="Maybe">     223:</span> <span class="k">   - detect write after the end of the buffer (buffer overflow)</span>
<a name="224" /><span class="Maybe">     224:</span> <span class="k"></span>
<a name="225" /><span class="Maybe">     225:</span> <span class="k">   The function does nothing if Python is not compiled is debug mode. */</span>
<a name="226" /><span class="Maybe">     226:</span> <a href="macros_ref.html#_UHlBUElfRlVOQ18w"><span class="b">PyAPI_FUNC</span></a><span class="f">(</span><span class="m">void</span><span class="f">)</span> <span class="b">PyMem_SetupDebugHooks</span><span class="f">(</span><span class="m">void</span><span class="f">)</span><span class="f">;</span>
<a name="227" /><span class="Maybe">     227:</span> <span class="f">#</span><span class="n">endif</span>
<a name="228" /><span class="Maybe">     228:</span> 
<a name="229" /><span class="False">     229:</span> <span class="f">#</span><span class="n">ifdef</span> <span class="b">__cplusplus</span>
<a name="230" /><span class="False">     230:</span> <span class="f">}</span>
<a name="231" /><span class="Maybe">     231:</span> <span class="f">#</span><span class="n">endif</span>
<a name="232" /><span class="Maybe">     232:</span> 
<a name="233" /><span class="True">     233:</span> <span class="f">#</span><span class="n">endif</span> <span class="k">/* !Py_PYMEM_H */</span>
<a name="234" /><span class="True">     234:</span> </pre>
  </body>
</html>
